Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d1 / freemacs.arc / REFERENC.DOC < prev next >

Wrap

Text File | 1988-03-17 | 30.9 KB | 715 lines

The Reference Guide to Emacs Functions MINT: The input to the MINT processor consists of strings of characters. Certain combinations of strings, namely #(...) and ##(...), invoke functions. The body of the function is separated by commas into arguments (no commas means one argument) that are evaluated from left to right. The first argument is assumed to be the name of a function, and the value is computed by supplying the arguments to the function. If the function was the single sharp #(...) form, the value is rescanned; otherwise the value is passed over without rescanning. The form (...), where the interior string contains balanced parentheses, protects the interior string from evaluation. The processor simply strips the outer parentheses and passes by the interior. If '**' is the multiply function and '++' the addition function, then the input string ((3+4))*9 = #(**,#(++,3,4),9)' will evaluate to (3+4)*9 = 63 Note that 3+4 is to be surrounded by parentheses. To prevent them from being interpreted as protection parentheses, they must themselves be surrounded by a pair of protection parentheses. Interior to the processor are three structures: the active string, the neutral string, and the scan pointer. A convenient visualization is to think of the neutral string on the left, the scan pointer in the middle, and the active string on the right. The scan pointer always points at the left of the active string, looking at the first character. Normally characters move from the active to neutral string, where they are accumulated until there are enough to form all the arguments of some function. Then the function is evaluated and the result put back in the active or neutral string according to the function type. The scanning algorithm: The algorithm consists of 10 numbered steps. When the processor is executed, it begins by going to step 1. Throughout the algorithm there are mentions of marking the neutral string in various ways. Think of these markers as flags attached to the affected characters (of course, the markers are accompanied by pointers, pointing backwards though the neutral string). 1. Clear the processor by emptying the neutral string, deleting the contents of the active string, if any, filling the active string with the string #(d,#(g)), and setting the scan pointer to the first character of the active string. Perform a redisplay of the current text buffer if there are no characters in the input buffer. 2. Examine the character under the scan pointer. If there is none - that is, if the active string is the null string - return to step 1. Note that the neutral string may still contain characters. 3. If the character under the scan pointer is a horizontal tab, carriage return, or line feed, delete it, advance the scan pointer, and return to step 2. 4. If the character under the scan pointer is a left parenthesis, delete it and scan forward until the matching right parenthesis is found. After all of the intervening characters have been moved without change to the neutral string, the right parenthesis deleted, and the scan pointer moved to the character following the right parenthesis, return to step 2. If the matching right parenthesis cannot be found, go back to step 1 without giving an error. 5. If the character under the scan pointer is a comma, delete it, mark the rightmost character of the neutral string as the end of one argument, advance the scan pointer, and return to step 2. 6. If the character under the scan pointer is a sharp sign and the next character is a left parenthesis, an active function is beginning. Delete the sharp sign and the left parenthesis, advance the scan pointer beyond them, mark the rightmost character of the neutral string as the beginning of both an argument and an active function, and return to step 2. 7. If the character under the scan pointer is a sharp sign and the next two characters are another sharp sign and a left parenthesis, a neutral function is beginning. Delete the triple ##(, advance the scan pointer beyond them, mark the rightmost character of the neutral string as the beginning of both an argument and a neutral function, and return to step 2. 8. If the character under the scan pointer is a sharp sign that did not meet the conditions of step 6 or 7, move it to the right end of the neutral string, advance the scan pointer, and return to step 2. 9. If the character under the scan pointer is a right parenthesis, a function is ending. Delete the right parenthesis, advance the scan pointer, and mark the rightmost character of the neutral string as the end of an argument and the end of a function. Now the neutral string from the rightmost begin function marker to the just inserted end function marker constitutes a MINT function invocation. (If there is no begin function marker in the neutral string, return to step 1 without giving an error.) The first argument is assumed to be the name of a MINT function. If the argument is two characters long, and is the name of a built-in function, that function is evaluated with the given arguments: extra arguments are ignored and missing ones are automatically supplied as the null string. If the function is not built-in, a default built-in function is executed. The result of the function is catenated to the right of the neutral string if the function was marked as neutral and to the left of the active string if marked active; in the latter case, the scan pointer is reset to the leftmost character of the new active string. Check the head of the keyboard buffer. If the key is the break key for your system (Z-100 uses Shift-Help, IBM-PC uses Ctrl-Prtsc) then input that key and go to step one, otherwise return to step 2. 10. If the character under the scan pointer did not meet any of the conditions of steps 3 through 9, attach it to the right of the neutral string, delete it from the active string, advance the scan pointer, and return to step 2. The MINT functions: The MINT functions are listed here in their active forms, but each can be called in neutral mode as well. The value of a function is always a string; any function, particularly those whose most important activity is a side effect, might return the null string. In addition to the structures already mentioned, the processor can store strings in an area called string storage. Each string has three parts: a string name, which may be any string whatsoever; a string body, which may also be any string; and a string pointer, which initially points just in front of the first character of the string body. The string pointer always points just before the body, just after it, or between two characters; that is, it always points into a gap between characters. Form bodies may include ordinal parameter markers intermixed with their characters. Each such marker has some positive integer associated with it, and these integers need not be distinct. #(ds,N,B) "Define String" This null-valued function creates a string with name N and body B with its string pointer just before the first character of B. If there is a string with name N already, its previous body and string pointer are lost. #(mp,N,P1,P2,...) "Make Parameter" This null-valued function creates parameter markers in the string N. The non-null arguments P1,P2..., are processed in turn from left to right (null arguments are ignored). Argument Pi is processed in the following way. The body of string N is scanned from left to right for the first substring exactly equal to Pi. The matching substring must not contain any already-existing parameter markers. If it does not, the substring is taken out of the string body and an ordinal parameter marker numbered i replaces it. The matching process begins again at the character following the marker. The string pointer is replaced at the left end of the string when the searching is finished. A string may be searched more than once. Parameter markers are represented by characters in the range 128..255. Parameter marker 128 is ignored, 129 corresponds to P1, 130 corresponds to P2, etc. #(N,A1,A2,...) "Default" The value of this function is the body of the string N with its parameter markers filled in. All those parameter markers numbered 1 are filled with argument N, those numbered 2 with A1, those numbered 3 with A2, and so on. Remember that excess arguments are ignored and missing ones are supplied with the null string. #(gs,N,A1,A2,...) "Get String" The value of this function is the body of the string N with its parameter markers filled in. All those parameter markers numbered 1 are filled with argument A1, those numbered 2 with A2, and so on. Remember that excess arguments are ignored and missing ones are supplied with the null string. #(go,N,Z) "Get One (character)" The value of this function is the character immediately following the string pointer in the string N. The string pointer is advanced just beyond the selected character. If the string pointer is already at the right end of the string, the function value is argument Z returned in active mode regardless of the mode of the function call. #(gn,N,D,Z) "Get N (characters)" The value of this function is a substring of string N. Starting at the string pointer and reading right the value is D characters of the string body. (The interpretation of a string as a number will be discussed later.) The string pointer is moved to point between the selected substring and the first unread character. If D is zero, the value is null and the pointer does not move. If the string pointer should move off the end of the string, the function value is argument Z returned in active mode regardless of the mode of the function call. #(fm,N,X,Z) "First Match" The string N is searched rightward from the string pointer for a substring containing no parameter markers and exactly matching argument X. If such a match is found, the value of the function is the substring of the string from the original location to the character immediately preceding the match and the string pointer is moved just before the character immediately following the matched substring. If no match is found, the argument Z is returned in active mode regardless of the mode of the function call, and the string pointer is stationary. #(rs,N) "Restore String" This null-valued function restores the string pointer of string N to its initial position just before the first character of the string. #(es,N1,N2,...) "Erase String" This null-valued function erases the strings named N1, N2, ..., from string storage. MINT performs arithmetic on strings of decimal characters. The arithmetic value of a string is given by the longest suffix of the string that can be described exactly as all decimal digits preceded by at most one plus or minus sign. Thus the value of 3 is three; of a-4 is negative four; of ++++200 is two hundred; and of the null string and of abc the null string. The null string acts as zero in arithmetic operations. The result of an arithmetic operation is itself at least such a decimal string with no leading zeros or plus signs for positive results and with zero represented as 0. #(++,A,B) "Add" The value of this function is the sum of the arithmetic values of arguments A and B with the nonnumeric prefix of A prefixed to the result. The prefix of B is lost. #(--,A,B) "Subtract" The value of this function is the result of subtracting the arithmetic value of argument B from that of argument A. The nonnumeric prefix of A is prefixed to the resultant decimal string, and the prefix of B is lost. #(**,A,B) "Multiply" The value of this function is the result of multiplying the arithmetic value of argument B to that of argument A. The nonnumeric prefix of A is prefixed to the resultant decimal string, and the prefix of B is lost. #(//,A,B) "Divide" The value of this function is the numeric value of argument A divided by the numeric value of argument B, and the result is prefixed with the nonnumeric prefix of A. The prefix of B is lost. The division operation is done in integer mode, and only the integral portion of the quotient is retained. #(%%,A,B) "Modulo" The value of this function is the numeric value of argument A modulo the numeric value of argument B, and the result is prefixed with the nonnumeric prefix of A. The prefix of B is lost. The modulo operation is done in integer mode, and only the integral portion of the modulus is retained. #(g?,A,B,T,F) "Greater" The value of is function is the argument T if the arithmetic value of argument A is greater than the arithmetic value of argument B, and is argument F otherwise. #(==,A,B,T,F) "Equality" The value of this function is the argument T if the argument A is exactly equal, as a string, to the argument B, and is the argument F otherwise. Notice that T and F may be any strings whatever. #(ll,A,F) "Load Library" This null-valued function retrieves all of the strings stored in the file specified by argument A. The strings are brought back to string storage, and if some of the strings are already in string storage, their values are overwritten. If the argument F is non- null, then string storage is cleared before loading. #(sl,A,F1,F2,...) "Save Library" This null-valued function stores the strings named by arguments F1, F2, ... in the disk file specified by argument A. #(ls,S,P) "List Strings" The value of this function is a list of all the strings whose names have a prefix of P. Of course, all strings have a null prefix, so if P is missing, then all strings are listed. The string names are separated by the string S. In addition to the active string, neutral string, and string storage, Emacs has a text buffer. This buffer is capable of holding any string of characters. Characters in the range zero through 127 may be viewed directly, while characters in the range 128 through 255 are viewed as the inverse video representation of the character that is 128 lower in value. The two character combination Carriage Return followed by Line Feed is considered a newline character, distinct from all other characters. Emacs considers the two characters to be indivisible. Any operation performed on one is performed on the other. Usually a newline character may be considered as one character, except that #(rm,>) will return a newline as two characters. The text buffer is most often accessed at a particular position called the point. The point is the place at which all insertions and deletions take place. The cursor on the screen is placed at the point. A mark is another position in the file, used to delimit block operations, and can be used to set the point. A mark is specified by a ASCII character. Emacs defines certain marks, called system marks, to have a special value. The meanings of all the valid marks are given in a table below. Any mark, system or user, may be used when a mark is called for. All the user marks are initially set to the beginning of the file. Once a mark is set, the mark "sticks" to the character at the right of the mark, or eof if that's the case. Therefore, the user marks tend to the end of the file. The global user marks are always available for use. The number of global marks is controlled by the value of a negative argument to the primitive 'pm'. For example, '#(pm,-3)' creates three global marks - @, A, and B. Creating global marks destroys all local marks. The local user marks are arranged as a stack. The primitive 'pm' is used to push and pop marks. If you wish to use two local marks, then you would execute '#(pm,2)'. This creates two new marks, 0 and 1, which both have the value of the current point. When you are finished using the marks, you would execute '#(pm)'. You may use at most ten local user marks at once. Mark Character Meaning ___________ _______ @ through Z Global user marks 0 through 9 Local user marks. < The character to the left of the point. > The character to the right of the point. { The first blank character to the left of the point. } The first blank character to the right of the point. - The first non-blank character to the left of the point. + The first non-blank character to the right of the point. [ The beginning of the file. ] The end of the file. ^ The beginning of this line. $ The end of this line. . The point. #(rd,F,L) "Redisplay" This null-valued function causes the screen to match the text in the text buffer. The lines on the screen which do not match the lines in the text are redrawn. If the argument F is not null, the screen is completely redrawn. If the input buffer is not empty, that is, if a key is waiting to be executed, redisplay is not performed. This prevents the input buffer from overflowing. If the numeric argument L is non-zero, the screen is positioned so that the point is on that screen line. L must be in the range #(lv,t) through #(lv,b), otherwise the point will not be moved. #(ba,N,F) "Buffer Allocate" This function will create and select a new buffer if N is zero. The result is the new buffer's number. The result is zero if there is not enough memory for a new buffer. If N is positive, then the buffer numbered N is selected. The result is zero if there is no buffer numbered N. If N is negative, the result is the number of the currently selected buffer, which remains selected. The buffer is selected cheaply if the argument F is non- null. In this case, the buffer appears full. This is provided so that a buffer may be visited quickly. #(bi,N,M) "Buffer Insert" This function will insert into the current buffer all the text in buffer N between buffer N's point and buffer N's mark 'M'. #(is,S) "Insert String" This null-valued function inserts the argument S before the point. If the buffer becomes full, the string is not inserted. #(ss,S) "Set Status" This null-valued function displays the argument S at the bottom of the current window. #(an,S) will temporarily overwrite the bottom line of the screen. The next redisplay will rewrite the status string. #(an,S,F) "Announce" This null-valued function displays the string given in argument S on the status line. If argument F is null, then the cursor is left following the string. If argument F is not null, then the cursor is not positioned after the string. If the argument S is null then the next redisplay will rewrite the argument S given in the previous #(ss,S). Guidelines for announcing things with #(an): If the string ends in ..., you are expected to wait for the operation to complete. If the string ends in ?, you are expected to type a single character. If a choice is not given, then you must type 'y' or 'n'. If the string ends in !, an error has occurred. If the string ends in :, you are expected to type a string terminated by return. If the string doesn't end in one of the above, it's an advisory message, and and is ignorable. #(lv,F) "Load Variable" This function returns a numeric value which is dependent upon the value of the argument F. A table of the various values returned versus the first character of F follows: First character of F Value returned -------------------- -------------- B Background color (0..7) initially 0 F Foreground color (0..7) initially 7 p percent of screen allocated to the top window o buffer being displayed in "other" window (0..) if 0, then there is no other window. u window currently in use (1..2) l number of current line (1..32767) n number of lines (1..32767) r row on screen (-32768..32767) c column on screen (1..255) t top line of screen (1..24) b bottom line of screen (1..24) m flag, zero if buffer not modified (0..1) s percentage of top screen that scrolls (0..100) f percentage of bot screen that scrolls (0..100) w redisplay shows whitespace (0..1) none of the above number of current line (1..32767) If #(lv,T) <= #(lv,R) <= #(lv,B) then the cursor is on the screen. Otherwise, the cursor is below or above the screen respectively. #(sv,F,V) "Store Variable" This function sets a numeric value which is dependent upon the value of the argument F. A table of the various values set versus the first character of F follows: First character of F Value set -------------------- -------------- B Background color (0..7) initially 0 F Foreground color (0..7) initially 7 p percent of screen allocated to the top window o buffer being displayed in "other" window (0..) if 0, then only one window will be used. u window currently in use (1..2) l the point is moved to the first character of the line V (1..32767) n none r the next redisplay moves the cursor to the Vth row on screen (1..24) c the point is moved to column on screen (1..32767) t none b none m flag, zero if buffer not modified (0..1) s percentage of top screen that scrolls (0..100) f percentage of bot screen that scrolls (0..100) w redisplay shows whitespace (0..1) none of the above number of current line (1..32767) #(pp) "Pick Position" This function returns a value corresponding to the position specified by the pick device. The value consists of two numbers separated by a comma. The first number is the column being picked, and the second number is the row being picked. #(st,S) "Syntax Table" This null-valued function sets the form to be used as the syntax table. The syntax table is used to determine the syntax of a particular character. The first character in the form gives the syntax for the null character. The 32nd character in the form gives the syntax for the space character, etc. If the form is less than 256 characters in length, those characters that fall off the right end have random syntax. If argument S is null, the form previously selected as the syntax table is deleted, or no form is selected as the syntax table, the syntax reverts to the default syntax: 0-9, A-Z, and a-z are the only non-blank characters. The newline character is neither blank nor non-blank. The characters are interpreted as bit fields. The following bits have the given meaning: bit meaning --- ------- 0 =0 if blank, =1 if non-blank. 7-1 not used. #(pm,S,E) "Push/Pop Mark" This null-valued function allocates marks. If the numeric argument S is positive and not zero, that number of local marks are allocated. If the numeric argument S is negative, that number of permanent marks are allocated and all local marks are destroyed. If the numeric argument S is zero, the current local marks are deallocated, and the previous local marks become available again. If stack overflow or underflow occurs, the argument E is returned active. #(sm,M,V) "Set Mark" This function sets the mark given by argument M to the mark given by argument V. If V is null, the point is used. #(sp,M) "Set Point" This null-valued function causes the point to be set to the mark given by argument M. Argument M may be a single mark or a sequence of marks. #(sp,MN) is equivalent to #(sp,M)#(sp,N). #(dm,M) "Delete to Mark" This null-valued function causes all text between the point and the mark given by argument M to be deleted. Deleting large amount of text can take a long time, but #(dm,]) when the point is at the beginning of file is specially coded and takes little time. #(rm,M,V) "Read Mark" This function returns the characters between the point and the mark given by argument M. If there is not enough string space, the argument V is returned active. #(rc,M) "Read Count" This function returns the number of characters between the point and the mark given by argument M. #(mb,M,Y,N) "Mark Before" This function returns Y if the mark M is before the point, and N if the mark is after the point. #(lp,S) "Look Pattern" This function sets the pattern to be searched for with #(lk). No characters are special, but null should not be used. #(lr,S) "Look Regexp" This function sets the pattern to be searched for with #(lk). Certain characters have special meanings: \ causes the following character to have no special meaning. ^ matches the beginning of a line. $ matches the end of a line. ? matches any single character. [,;] matches , or ; (for instance). [a-z] matches a-z (for instance). [~a-z] matches anything but a-z (for instance). * causes the previous character to be matched zero or more times. #(lk,S,E,F,L,N) "Look" This function searches between marks S and E for the pattern specified by #(lp). If the pattern is found, the mark F is set to the point before the found string, and mark L is set to the point after the found string. If S is not found, neither mark is changed, and argument N is returned active. If S is null, then it defaults to the beginning of the file. If E is null, then it defaults to the end of the file. If F is null, it defaults to mark zero. If L is null, it defaults to mark one. #(rf,N) "Read File" This function reads the file named in argument N into the text buffer to the left of the point. If no error occurs, the null string is returned. If an error occurs, an error message is returned. The possible messages are: File not found File too large End of file #(wf,N,M) "Write File" This function writes text to the file named in argument N. The text to be written is located between the point and the mark given in argument M. If no error occurs, the null string is returned. If an error occurs, an error message is returned. The possible messages are: Directory Full Disk Full #(ff,N,S) "Find Files" This function returns the names of all the files that match argument N. Wildcards are allowed. Each file name is separated by argument S. #(rn,O,N) "Rename file" This function renames the file given in argument O to the name given in argument N. Wildcards are not allowed. If an error occurs, an error message is returned. The possible messages are: Rename error #(de,N) "Delete File" This function deletes the file named in argument N. Wildcards are not allowed. If an error occurs, an error message is returned. The possible messages are: File not found #(ev) "Environment" This function reads the MS-DOS environment. All the environment strings are defined as strings with a prefix of "env.". In addition, the arguments passed to emacs on the run line are defined as "env.RUNLINE". The switch character used by MS-DOS is defined as "env.SWITCHAR". #(it,T) "Input Timed" This function waits for T hundreths of a second for a key to be pressed on the keyboard. If T is zero, the character (if one has been pressed) is not input. If no key is pressed, "Timeout" is returned. If a key is pressed before the timeout interval, then one of the following values is returned: C-@ Control-@ C-A Control-A ... The rest of the control characters are fashioned similarly. C-_ Control-_ Space (a single space) ! Bang ... The rest of the printables just return themselves Delete Emacs is written to be as machine independent as possible. Therefore, your Emacs implementation may not implement all of the following keys. If the key has a shifted version, then the key name is preceded by 'S-' unless it is a standard ASCII character. For example, C-_ is not returned as C-S--. If your implementation has a Meta key (sometimes called Alt), then the key name from the list below (as well as those above) is preceded with 'M-'. Note that other Emacs define control and meta keys to be C-M-x whereas Freemacs defines control and meta keys to be M-C-x. BackSpace Not the same as C-H Tab Not the same as C-I Return Not the same as C-M Escape Not the same as C-[ Enter Not the same as C-M Help S-x Shift version of any key (only non-ASCII). C-x Control version of any key (only non-ASCII). M-x Meta version of any key. F0,F1,F2,F3,F4,F5,F6,F7,F8,F9,F10,F11,F12 Etc. Ins Del I Chr D Chr Ins Line Del Line Up Arrow Down Arrow Right Arrow Left Arrow Home End Pg Up Pg Dn Break Sys Req KP+,KP-,KP. Keypad keys KP0,KP1,KP2,KP3,KP4,KP5,KP6,KP7,KP8,KP9 Left Down Mouse buttons Left Up Right Down Right Up Middle Down Middle Up #(bc,V,F,T) "Base Conversion" This function converts the Value given in argument V From the base given in argument F To the base given in argument T. Several different characters are used in the From and To arguments, and are given in the table below. From defaults to ASCII, and To defaults to decimal. Character Meaning a or A ASCII character. d or D decimal number. h or H hexadecimal number. o or O octal number. b or B binary number. #(nc,A) "Number of Characters" This function returns the number of characters in the argument A. #(dt) "Date" This function returns the date in the form "mm/dd/yy" regardless of the country setting. #(tm) "Time" This function returns the time in the form "hh:mm:ss" regardless of the country setting. #(n?,F,Y,N) "Name exists?" This function tests for the existance of the string F and returns Y if found and N if not found. #(a?,A,B,Y,N) "Alphabetic?" This function returns Y if A is alphabetically less than B and N otherwise. #(sa,A,B,C,...) "Sort Ascending" The arguments A, B, C, etc. are returned in alphabetic ascending order seperated by commas. #(xy,X,Y) "X Y" This function sets the screen location at which the next overwrite will occur. #(ow,S) "Over Write" This function overwrites the screen with the string S. The next redisplay will rewrite the buffer's lines. Subsequent over writes are equivalent to a single over write. That is, #(ow,A)#(ow,B) is equivalent to #(ow,AB) #(hl,N) "Halt" Exits Emacs to MS-DOS with a return code of N (decimal). Emacs will halt with a return code of one if 'emacs.ed' cannot be found. #(db) "Debug" Executes an interrupt 3 which should enter a debugger. Do not use this if you haven't run DEBUG first! #(ex,F,A) "Execute Program" Executes the program F, which must be a fully qualified pathname with an extension. The arguments to the program are in A. During the execution of the program, anything written to the device '@' will be inserted into the current emacs buffer. #(ef,F,A,M) "Execute Filter" Executes the program F, which must be a fully qualified pathname with an extension. The arguments to the program are in A. If the program inputs from stdin, the input will be taken from the current buffer. Only text from the point up to the mark M will be used. If the mark is before the point, then no text will be used. Any text used as input to the program gets deleted. If the program doesn't do input, nothing will be deleted. Anything written to stdout will be inserted into the current emacs buffer.